package de.mmis.core.base.infrastructure;

import de.mmis.core.base.event.Observable;

public interface Infrastructure extends Observable<InfrastructureEvent> {

	/**
	 * remove the device from the infrastructure
	 * 
	 * @param device
	 *            A device description, not a pattern.
	 * @throws InfrastructureException
	 *             when the infrastructure is not running or when the
	 *             description was a pattern.
	 */
	public abstract void removeDevice(PublishedDeviceDescription device)
			throws InfrastructureException;

	/**
	 * Search for devices that match the pattern. The answers are
	 * {@link InfrastructureEvent}s.
	 * 
	 * @param pattern
	 *            a {@link PublishedDeviceDescription}
	 * @throws InfrastructureException
	 *             when the infrastructure is not running
	 */
	public abstract void searchDevice(PublishedDeviceDescription pattern)
			throws InfrastructureException;

	/**
	 * Search for a single device that matches the pattern. This is a
	 * convenience method making it unnecessary to wait for the
	 * {@link InfrastructureEvent}. Nevertheless the events will be generated.
	 * 
	 * @param pattern
	 *            a {@link PublishedDeviceDescription}
	 * @param timeout
	 *            maximum time span (in milliseconds) to wait for an answer.
	 * @return a device matching the pattern, or null if we got no answer within
	 *         the specified timeout.
	 * @throws InfrastructureException
	 *             when the infrastructure is not running
	 */
	public abstract PublishedDeviceDescription searchSingleDevice(
			PublishedDeviceDescription pattern, int timeout)
			throws InfrastructureException;

	/**
	 * Adds the device to the infrastructure
	 * 
	 * @param device
	 *            A device description, not a pattern.
	 * @throws InfrastructureException
	 *             when the infrastructure is not running or when the
	 *             description was a pattern.
	 */
	public abstract void addDevice(PublishedDeviceDescription device)
			throws InfrastructureException;

	/**
	 * Stops the infrastructure.<br/>
	 * Other VMs are notified that our devices are removed <b>dirty</b>. The
	 * application has to remove it's devices first.<br/>
	 * Observers of this VM get an {@link InfrastructureEvent} with type
	 * SHUT_DOWN.
	 */
	public abstract void stop();

}